commit c3f5671b4eb04fba2cae977039bcf15265cb3b0e from: Anton Kasimov date: Fri Aug 21 14:50:20 2026 UTC Partial вставки изображения commit - 5a365c2607655acb416397319c5c362e1bbb4f15 commit + c3f5671b4eb04fba2cae977039bcf15265cb3b0e blob - 8d00dd266fc4970b94aee4cc71061253377837bc blob + 35887bf88046dd1ff00fb21ee83241b4d208ace8 --- README.md +++ README.md @@ -1,176 +1,532 @@ # Набор шаблонов для сайтов Hugo от Radium -## Подключение темы на сайте -Настройте [слияние](https://gohugo.io/configuration/introduction/#merge-configuration-settings) конфигурации в hugo.toml, указав: +## Подключение темы +Настройте [слияние конфигурации](https://gohugo.io/configuration/introduction/#merge-configuration-settings) в `hugo.toml`: + ```toml _merge = 'deep' ``` +Это позволяет переопределять параметры, заданные темой, в конфигурации сайта. + ## Параметры -Все используемые параметры должны содержаться в настройках сайта в .Params.radium -publisher -: ссылка на профиль публикатора для элементов JSON-LD. -external_rel -: rel по умолчанию для абсолютных ссылок. +Все параметры темы находятся в пространстве имён `radium`: -## render hooks +```text +.Params.radium +``` + +Параметры сайта доступны через: + +```go-html-template +site.Params.radium +``` + +Параметры также могут быть переопределены для отдельной страницы через front matter. + +### Общие параметры + +`publisher` +: ссылка на профиль издателя для элементов JSON-LD. + +`external_rel` +: значение `rel` по умолчанию для абсолютных ссылок. + +### Изображения + +Параметры обработки изображений находятся в: + +```text +.Params.radium.images +``` + +`widths` +: набор ширин для генерации адаптивных изображений. + +`sizes` +: значение атрибута `sizes` по умолчанию. + +`mode` +: режим обработки изображения: `auto`, `lossy` или `lossless`. + +Параметры могут задаваться: + +1. в конфигурации темы; +2. в конфигурации сайта; +3. во front matter страницы; +4. непосредственно при вызове `image`. + +Более специфичное значение имеет приоритет. + +## Render hooks + ### render-link -Вставляет ссылку с разрешённым назначением ссылки. -Для абсолютных ссылок указывает rel из настроек сайта или значение по умолчанию `noopener noreferrer external`. +Вставляет ссылку с разрешённым набором атрибутов. + +Для абсолютных ссылок устанавливает `rel` из настроек сайта или значение по умолчанию: + +```text +noopener noreferrer external +``` + ### render-blockquote -[Вставляет](https://gohugo.io/render-hooks/blockquotes/) блок цитаты с указанием источника и заголовка, а также блок alert. +[Вставляет](https://gohugo.io/render-hooks/blockquotes/) блок цитаты с указанием источника и заголовка, а также поддерживает блоки alert. + ## Шаблоны + ### baseof -Базовый шаблон, включающий индексирование Pagefind только для main тега. -Для тега html устанавливается язык и направление, если оно явно прописано в настройках языка. -В шаблоне подключаются partial head, header, footer. -Блок main должен быть переопределён в отдельных шаблонах. -Блок head может быть переопределён в отдельных шаблонах, если требуется добавить что-то в тэг head. +Базовый шаблон сайта. + +Включает индексирование Pagefind только для элемента `main`. + +Для элемента `html` устанавливает язык и направление текста, если направление явно указано в настройках языка. + +Подключает partials: + +* `head`; +* `header`; +* `footer`. + +Блок `main` должен быть переопределён в дочерних шаблонах. + +Блок `head` может быть переопределён, если требуется добавить дополнительные элементы в ``. + ## Partials ### attrs -Рендерит словарь из ключей и значений в виде атрибутов тэга. -Для булевых значений вставляется или не вставляется соответствующий ключ без значения. +Преобразует `dict` атрибутов в строку HTML-атрибутов. + +Обычные значения выводятся в виде: + +```html +class="example" +``` + +Булевы значения обрабатываются как HTML boolean attributes: + +* `true` — выводится только имя атрибута; +* `false` — атрибут не выводится. + +Например: + +```go-html-template +{{ partial "attrs.html" (dict + "class" "video" + "controls" true + "autoplay" false +) }} +``` + +создаёт: + +```html +class="video" controls +``` + ### pick -Отбирает из dict ключи, входящие в массив allowed. +Возвращает новый `dict`, содержащий только ключи из переданного массива `allowed`. + +Например: + +```go-html-template +{{- $attributes := partial "pick.html" (dict + "dict" .Params + "allowed" (slice "class" "id") +) -}} +``` + +Значения `false`, `0` и пустые строки сохраняются. + ### image -Отображает изображение, передаваемое в .image. -.image должен быть ресурсом, полученным через .Resources.Get* или resources.Get*. -Для SVG изображений производит сжатие, а для всех остальных указывает ширину и высоту. +Отображает изображение, переданное в параметре `image`. -Если установлен .alt, то устанавливает атрибут alt. +`image` должен быть Hugo image resource, например полученным через: +```go-html-template +.Resources.Get +resources.Get +resources.GetRemote +``` + +Для изображений, которые Hugo умеет обрабатывать, partial создаёт адаптивые варианты изображения. + +Лесенка размеров определяется параметром `widths`. Если он не передан, используются настройки страницы или сайта из: + +```text +radium.images.widths +``` + +Размеры больше исходного изображения не создаются. Исходная ширина при этом всегда добавляется в `srcset`. + +Например, для исходного изображения шириной `4000px` и лесенки: + +```text +480 768 1024 1440 1920 +``` + +будут доступны варианты: + +```text +480 768 1024 1440 1920 4000 +``` + +Для исходного изображения шириной `1300px`: + +```text +480 768 1024 1300 +``` + +#### Lossy-изображения + +Для lossy-изображений создаются: + +* AVIF; +* WebP. + +В HTML используется ``, где AVIF является предпочтительным форматом, а WebP — fallback. + +JPEG автоматически считается lossy. + +#### Lossless-изображения + +Для lossless-изображений создаётся lossless WebP. + +PNG и BMP автоматически считаются lossless. + +Для форматов, режим которых нельзя однозначно определить по MIME-типу, следует явно передать: + +```text +mode = "lossy" +``` + +или: + +```text +mode = "lossless" +``` + +#### Исходный формат + +Если исходное изображение уже находится в целевом формате и используется в исходном разрешении, оно не перекодируется повторно. + +#### SVG и другие необрабатываемые изображения + +Изображения, которые Hugo не умеет преобразовывать, передаются без изменения. + +SVG дополнительно минифицируется. + +Для SVG можно вручную передавать `width` и `height` через `attributes`. + +#### Атрибуты + +Дополнительные атрибуты `` передаются через `attributes`: + +```go-html-template +{{- partial "image.html" (dict + "image" $image + "page" . + "attributes" (dict + "alt" "Описание изображения" + "class" "photo" + "loading" "lazy" + "decoding" "async" + ) +) -}} +``` + +Если `width` и `height` не заданы, partial указывает размеры автоматически, когда Hugo может их определить. + +Если передан только один из этих атрибутов, второй вычисляется с сохранением соотношения сторон. + +Параметр `sizes` можно передать непосредственно: + +```go-html-template +{{- partial "image.html" (dict + "image" $image + "page" . + "sizes" "(max-width: 900px) 100vw, 900px" +) -}} +``` + ### logo + Отображает логотип со ссылкой. Параметры: -- image - имя ресурса сайта с логотипом (img/logo.svg) -- class - класс ссылки, содержащей логотип (logo) -- link - ссылка, которая будет указана для логотипа (главная страница с учётом языка) -- alt - атрибут alt изображения (Logo image) +`image` +: имя ресурса сайта с логотипом. По умолчанию `img/logo.svg`. -### head/favicon, head/apple-touch-icon -Связывают страницу с имеющимися favicon или apple-touch-icon. -Для поиска favicon применяется маска {,**/}favicon.*, а для apple-touch-icon - {,**/}apple-touch-icon*.png +`class` +: класс ссылки, содержащей логотип. По умолчанию `logo`. +`link` +: ссылка логотипа. По умолчанию главная страница с учётом языка. + +`alt` +: значение атрибута `alt`. По умолчанию `Logo image`. + +### head/favicon + +Связывает страницу с найденными favicon. + +Для поиска используется маска: + +```text +{,**/}favicon.* +``` + +SVG-файлы минифицируются. + +Если Hugo может определить размеры растрового изображения, у `` устанавливается атрибут `sizes`. + +### head/apple-touch-icon + +Связывает страницу с найденными Apple Touch Icon. + +Для поиска используется маска: + +```text +{,**/}apple-touch-icon*.png +``` + ### head/manifest -Связывает страницу с manifest.json, находящимся в корне assets/ +Связывает страницу с `manifest.json`, находящимся в корне `assets/`. + ### head/css -Подключает css/main.css +Подключает: + +```text +css/main.css +``` + ### head/js -Подключает js/main.js +Подключает: + +```text +js/main.js +``` + ### head/pagefind -Подключение стилей и скрипта, если окружение не является разработкой. +Подключает стили и скрипт Pagefind, если окружение не является development. + ### head/alternate -Указывает link alternate для других языков и форматом страницы. +Добавляет `` для других языков и форматов страницы. + ### head/base -Добавляет title, description и canonical в заголовок, а также meta charset + viewport. +Добавляет в ``: + +* `title`; +* `description`; +* canonical URL; +* `meta charset`; +* `viewport`. + ### head/social -Добавляет рендер встроенных шаблонов OpenGraph и Twitter Cards. +Добавляет встроенные шаблоны Open Graph и Twitter Cards. + ### schema -Подключает JSON-LD схемы для связанных объектов. -Принимает в контексте либо страницу, либо dict с ключами page и schema. -Схема - это строка или массив строк. +Подключает JSON-LD-схемы связанных объектов. -Подключение в head: +В контекст можно передать: + +* страницу; +* `dict` с ключами `page` и `schema`. + +`schema` может быть строкой или массивом строк. + +Пример: + ```go-html-template {{- partial "schema/json-ld.html" . | safeHTML }} ``` -или + +С явным указанием схемы: + ```go-html-template -{{- partial "schema/json-ld.html" (dict "page" . "schema" "BreadcrumbList") | safeHTML }} +{{- partial "schema/json-ld.html" (dict + "page" . + "schema" "BreadcrumbList" +) | safeHTML }} ``` -Если в Page Bundle есть файл <тип>.jsonld (например, Person.jsonld), он будет добавлен в список schema. +Если в Page Bundle находится файл `<тип>.jsonld`, например: -Если по итогу для страницы список schema будет пустым, то будет отрендерен [встроенный](https://gohugo.io/templates/embedded/#schema) шаблон. +```text +Person.jsonld +``` +соответствующая схема автоматически добавляется в список. + +Если в результате список схем пуст, используется [встроенный шаблон Hugo](https://gohugo.io/templates/embedded/#schema). + #### Статья -Для указания publisher в статье укажите publisher в Params страницы, либо в настройках сайта. +Для указания `publisher` укажите его в параметрах страницы либо в настройках сайта. + ## Shortcodes + ### include -Позволяет [вставить](https://gohugo.io/render-hooks/blockquotes/#pageinner-details) другой markdown файл в текущий. -Полезно при разделении частей страницы на несколько файлов. +Позволяет [вставить](https://gohugo.io/render-hooks/blockquotes/#pageinner-details) другой Markdown-файл в текущий. + +Полезно для разделения большой страницы на несколько файлов. + ### details -Корректный details, позволяющий рендерить html. -Аналогично [стандартному](https://gohugo.io/shortcodes/details/#article) shortcode, за исключением способа вызова — необходимо использовать вызов {{% details %}} для рендера внутреннего текста в качестве Markdown. +Создаёт `
` с возможностью рендеринга внутреннего содержимого как HTML/Markdown. +Аналогичен [стандартному shortcode Hugo](https://gohugo.io/shortcodes/details/#article), но для рендеринга внутреннего содержимого как Markdown следует использовать notation: + +```text +{{% details %}} +``` + ### a -Создаёт ссылку с атрибутами href, class, id, rel. -Полезно для установки rel. +Создаёт ссылку ``. -Вызывает partial/element. -Если необходимы другие атрибуты, то переопределите этот shortcode. +Поддерживаются атрибуты: +* `href`; +* `title`; +* `rel`; +* `target`; +* `class`; +* `id`; +* `download`; +* `referrerpolicy`; +* `hreflang`; +* `type`; +* `role`; +* `tabindex`; +* `aria-label`; +* `aria-current`; +* `aria-describedby`. + +Пример: + +```md +{{< a href="/file.pdf" download=true rel="nofollow" >}} +Скачать +{{< /a >}} +``` + ### section -Создаёт секцию с атрибутами class, id. -Поддерживает стандартную и markdown нотацию вызова. +Создаёт элемент `
`. +Поддерживаются атрибуты: + +* `class`; +* `id`. + +Поддерживает обычную и Markdown-нотацию shortcode. + ### video -Вставляет видео. -Поддерживает параметры: -- class -- poster -- loading -- height -- width -- src -- tabindex -- area-hidden +Создаёт элемент `